License UI Settings

This chapter explains the built-in license UI for Standard Project Type, if you are using other project type, it is your responsibility to implement your own license UI in your application's source code.

SoftwareShield implemented built-in license UI is HTML/Javascript based and rendered by Qt/Webkit engine

There are two built-in UI templates shipped with SoftwareShield IDE.

Here is the workflow of how to use the license UI templates:

1. A new project of Standard Project Type is created;
2. Customize the UI template in your favorite HTML editor;
3. Setup the UI event map and online URL base if the UI is deployed on the server side;
4. Setup whether to embed the UI into the application;

UI Template Content

When the standard project is built for the first time, SoftwareShield IDE will copy a built-in template (default one is ModernBootstrap) to the "ProjectDir\Src\UI_HTML", the content of the directory looks like this:

LMApp.config: Event-Page Mapping Configuration

From the HTML file names you might be able to guess the purpose of each page, they can also be previewed by drag and drop the web page file to your favorite web browser, the only file seems a little weird is lmapp.config, this is an internal text file in XML format, defines Event to Web page mapping and basic rendering parameters. Actually, it is the configuration XML file for so called LMApp (License Model Application), when game running, this file is parsed by a SoftwareShield LMApp execution engine which then installs event listeners, popping up proper HTML page for an incoming event.

You can view lmapp.config in a text editor, its content looks quite simple:

When SoftwareShield IDE build the license project, it will re-generate the lmapp.config file automatically (unless you disable this feature in IDE).

Javascript files

The most important sub-folder is "js\", let's browse this folder by double clicking it:,

There are several javascript files in the folder:

• bootstrap.min and jquery-2.0.2.min are standard library files downloaded from public web site, they should never be modified;

• gs5.js is the javascript programming interface for SoftwareShield native SDK, which we will look into it in more details in SoftwareShield Programming Guide. It also cannot be changed.

• shield.js is a helper utility based on gs5.js, providing useful functions and AJAX based Web api calling to CheckPoint server, you should not change this file.

• GS_Mapping.js is automatically generated by SoftwareShield IDE when project building, the IDE parses the license project settings and converts them into javascript code snippets and variables used by HTML pages. For example, the CheckPoint server settings are translated as a javascript object array, BuyNow URL becomes a global variable.

Should I Modify?

When customizing your own LMApp UI, it is sometimes confusing which files can be modified manually outside SoftwareShield IDE. As we have mentioned in previous sections that some files (lmapp.config and GS_Mapping.js}) are one-way generated files, any modifications to these files will be overwritten after next project build, so for most cases unless you know exactly what you are doing, it is highly recommended not to touch these files.

• UI_HTML\lmapp.config: The recommended way to modify this file is editing the UI HTML Options in IDE.

  If you have manually modified it, for example, you want to map events to different web pages than default ones, to stop IDE from overwriting your own version, the "Copy LM APP" checkbox must be checked off.

• **UI_HTML\jsSoftwareShield_Mapping.js: To change the background image, BuyNow URL, the way to launch web browser, etc. you should do it in IDE

When you add more javascript variables and functions, please put them in a new javascript file which can be referenced by related HTML pages. If for some reasons, you have modified GS_Mapping.js and do not want to lose your change, then you should check off the "Copy Javascript Files" option.

After all, it is simply a small HTML5/Javascript based mini application, you can add as many images and new page elements as you want, many SoftwareShield customers have developed very beautiful UI for their games and applications, you can even develop amazing start up UI by embedding video clips, audios and animation effects on the page to impress your potential customers.

When you feel comfortable with the SoftwareShield SDK/javascript programming interface, you can re-organize the UI pages and extend the UI features in your own way; For example, you can develop a license control panel page to manage a game's license (buy more game modules, activate, move, import/export, etc.), you can also add localization to the UI, change the default language according to current Windows system locale. There is no limit in SoftwareShield, if you are a Web programmer, customizing LMApp UI should not be much different than developing a javascript driven HTML5 based web site.

Another good news is that once you have developed a beautiful license UI for your product, it can be shared by your other products, you can simply copy the UI_HTML folder to the other project's "Src\UI_HTML" folder.

SoftwareShield will continue improving the license UI to make it more portable and easy to customize. We will also add more built-in templates in the future.

UI HTML Options ( Menu Item => Edit => UI Options )

Debug UI Pages

SoftwareShield helps you develop and debug HTML/Javascript based UI pages, clicks on the "Enable UI Debug", then you can inspect UI elements and run test scripts in a debug console, please refer to (Enable UI Debug) for details.

Wrap UI Pages

UI pages are HTML, Javascript and image files, once they are prepared there is no need to modify them at run-time, you might also want to protect them from spying eyes to keep your own technical secrets, SoftwareShield allows you wrap all of the UI pages by selecting the Wrap License UI Pages so they won't appear in your install directory.

UI Page Size

The default UI page dimension is: width = 800 pixel, heigth = 600 pixel.

You can change the page size in the UI options dialog box.

How to keep my modifications

• Copy LM APP: It is ON by default, when this option is turned on, the IDE will generate the configuration file (Src\UI_HTML\lmapp.config) automatically for each project build.

You must turn it off to avoid overwriting a modified lmapp.config otherwise all your changes to lmapp.config will be lost.

• Copy Javascript Files: It is ON by default. When this option is turned on, the IDE will copy system javascript files (gs5.js, shield.js) from UI template folder, and generates file Src\UI_HTML\jsSoftwareShield_Mapping.js automatically for each project build.

UI Deploy: Local or Online?

Now that you have developed a beautiful license UI, it is time to decide where to deploy it physically.

SoftwareShield IDE supports both local and online page hosting:

To host the UI pages online, you must check on the option Enable Online HTML Pages, then you should specify the "Base URL" properly.

For example, if you upload the license UI pages (the whole UI_HTML folder) to a web server sub-folder, you should make sure that sub-folder can be accessed publicly and is mapped and assigned a unique URL, Because these are static files so you can host them in any web hosting server.

Fallback to local pages when offline or page loading time-out

Hosting UI pages online is pretty good choice, you can upgrade them easily; however, what if your customer do not have an Internet connection, or the internet connection is unavailable or broken temporarily? In this case the protected application will simply terminate! however, if you have turned on the Fallback to local pages when offline option, the SoftwareShield IDE will also make a local copy of UI pages when project building, the SoftwareShield protected application will first detect if the Internet connection is available, if it is currently online, then the online UI pages will be rendered, otherwise the local UI pages will be rendered as fall back.

Page Loading Time Out

If the Internet is accessible but the connection speed is very slow, or your web hosting server is shut down or inaccessible, then SoftwareShield will switch to local pages automatically if it detects that the online pages cannot be loaded properly within a limited time (20 seconds by default).

Actually the page loading time out value applies to both online and offline page rendering:

Browse to local HTML pages from online page

Another interesting question is: Is it possible to browse to local HTML pages from online pages? It could happen when you are integrating with third party e-Commerce provider, your license UI pages are hosted on third party web server which has some technical limitation to browse to other online pages (such as Fastspring, after customer make the payment, we need to browse back to the local UI pages to activate the product. For security consideration, this kind of browsing (from Internet to local) is prohibited, however, SoftwareShield implements api to make it possible, please refer to (UI Page Hopping) for details.

How to Disable UI Popping

Sometimes it is quite annoying to see license UI popping up for customers, especially after the application has been fully purchased. SoftwareShield allows you to disable two most commonly used license UI pages (onStart, onExit) in the following ways:

• Start UI (onStart.html)

This UI page (mapped to onStart.htm by default) pops up when an entity will be accessed, it gives the end users a chance to activate the entity interactively. An application may have defined multiple entities and the application developers can decide whether to pop up onStart UI according to current license status:

1. The whole application (all entities) are unlocked

The onStart UI won't pop up only and only if all of the entities of the application have been fully activated. If there is one entity still runs in trial mode, then when this entity is accessed, the onStart UI will pop up for the end users to unlock the entity.

2. The entity being accessed is unlocked (default)

The onStart UI won't pop up if the entity being accessed is already unlocked. For example, there are two entities A and B, the entity A has been activated and B is still in trial mode; when A is accessed, the onStart UI won't pop up, but when B is accessed, the onStart UI pops up for the end users to unlock the entity.

3. Any entity is unlocked

The onStart UI won't pop up if any of the entities has been unlocked.

For example, your game can run in multiple modes, each mode is mapped to an entity; if a game player has made a payment to activate at least one game mode with a purchased serial number, then your game will not pop up the start-up license UI. Of course, as a game developer you may decide to prompt the players to unlock more modes, it can be implemented inside the game with SoftwareShield SDK.

4. let the code inside onStart.htm decide what to do

The onStart UI is always popped up, it is the developer's responsibility to implement their own logic (in Javascript) to decide whether the UI should be hidden (bypassed) or fully rendered on the screen. It is the most flexible option, all of the other options can be implemented in javascript on this web page.

For example, you can add extra javascript logic in this UI page to check if there is a new version to upgrade, or display information to prompt your other products, or simply want to display a welcome screen (tips of the day, etc.); it is also good to display current license status and provide functions to unlock more entities, transfer license on the start page.

• Exit UI (onExit.html)

  This UI page (mapped to onExit.htm by default) pops up when the application terminate normally (not due to trial expired or error events). If the application exits because of license error or trial mode is expired, the onLicenseFail and onTimeExpire UI will be redirected accordingly.

1. The whole application (all entities) are unlocked (default)

If the application has been fully purchased (all entities are already activated), the onExit UI will not pop up, and the application will terminate silently.

2. Any entity is unlocked

If the application is partially purchased (at least one entity has been activated), the onExit UI will not pop up.

3. let the code inside onExit.htm decide what to do

The onExit UI is always popped up, it is the developer's responsibility to execute their own logic (implemented in Javascript) to decide whether to UI should be hidden (byassed) or actually rendered on the screen.

This is the last chance for you to display when the trial will expire (if the current app is running in demo mode), prompt other products for paid customers, or simply say thanks you to customers.

4. onExit UI is always disabled

If this option is selected, the onExit UI will never pop up, and it is safe not to ship the onExit.htm in your install package.

For example, your application is using the \emph{Always Lock} license model that must be activated to run, and you do not want to annoy your paid customers with any promption page on exiting, this is the right choice.

UI Template Editor ( Menu Item => Edit => UI Template Editor )

SoftwareShield built-in UI Templates publish some editable parameters (Background Image, Buy Now URL, etc.) that can be changed by the UI:

Here, you can specify the dimension of the web pages in pixels, you can also preview a selected web page.

Because Web page editing is a rather complex task, it is impossible to implement a full-fledged editor in the IDE, most web developers prefer working in their own familiar HTML editors, however, there is an interesting code input feature in the UI which can help you paste some commonly used code snippets. when you click the function() value area of Apply Template property, the Code Input UI will pop up:

Internally, all these modifications in this UI is persisted in the license project file, not in the UI folder (Src\UI_HTML) as we might have assumed, when project building, these settings are converted to corresponding Javascript elements in file Src\UI_HTML\jsSoftwareShield_Mapping.js.

For beginners, changing background image and Buy Now URL is enough to get them started, they will get a fully functional license UI quickly; for advanced web programmers, they only need to specify the dimension (Width and Height) in the template editor UI, they can ignore other stuffs and modify HTML pages greatly outside the IDE to fit their own tastes and requirements. However, they must make sure the GS_Mapping.js is included by the activation web pages so the license project defined CheckPoint server information can be accessed by other javascript methods.

How to rollback to default UI?

If you have messed up your local \path{Src\UI_HTML} files, or you simply want to restart from the system default template UI, you can rollback by pressing the Rollback to Default button:

The Rollback to Default button will only appear when the Current Project is selected in the top drop down list.

If the local UI exists, a warning message box will pop up asking your permission to overwrite the existing content:

Before pressing "Yes", please make sure you have made a copy of the current UI files somewhere.

You can also do it manually by copying a template from SoftwareShield IDE install directory to ProjectDir\Src\UI_HTML.

How to switch between UI templates?

When the project is created, the default UI template is used to initialize your UI template. When the Current Project item is selected in the top drop down list, the current UI template name is also displayed.

To switch to other UI template:

1. Select the new UI template in the template drop down list;

   The Set as Project Template button will appear if the active UI template is different from the project's template.

2. Press the Set as Project Template button.

   A warning message box will pop up telling you to confirm the modifications to your UI files, press "Yes" to continue.

How to backup and restore my own UI template?

To backup:

1. Select "Current Project" in the drop-down list;
2. "Open Folder" button to browse the UI templat folder;
3. Make a copy of the "UI_HTML" folder to a safe backup directory;

To restore:

Simply copy the previous UI backup to the Src\UI_HTML folder.

How to set Buy Now URL?

The Buy Now URL is a web url to display when the Buy Now button on the onStart.htm UI is pressed.

You can set up the Buy Now Url in either ways:

Hard Code Web Pages

You can edit the UI web source files and hard code the buy now url in the related UI pages (onStart / onExit):

  $('#buy-now-link').on('click', function() {
      gs.util.launchDefaultBrowser('http://www.myappstore.com/');
  });

Modify UI Template Property

In the UI template editor, depending on which UI template you are using, the url value can be set in the Template Properties:

1. Select the "Current Project" item in the top drop-down list;
2. Click the "Buy Now Url" property in the template properties panel, input the correct Web URL value;
3. Press "Save Changes" button to save the change to project file.

The UI template settings changed in the UI template editor are persisted in the license project file, not in the UI_HTML folder, when the IDE builds the project, these settings are converted to a javascript file (ProjectDir\Src\UI_HTML\jsSoftwareShield_Mapping.js).

Modify in UI Option Dialog (New in v5.3.6)

Because BuyNowURL is a commonly used UI property so we have integrated it in the IDE's UI Options dialog box: ( Edit => UI Options )

You can also specify that if the BuyNowURL will be rendered inside the app ( In-App-Purchase ) or out of app ( in the default web browser ).